COMMENT ⊗   VALID 00009 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002	Introduction:
C00004 00003	How to snarf and free the Dialnet port:
C00006 00004	How to do I/O to the Dialnet port:
C00010 00005
C00013 00006	How to do command functions to the Dialnet port:
C00016 00007
C00018 00008
C00023 00009
C00025 ENDMK
C⊗;
Introduction:

							MRC 4/29/79

     This document purports to describe the system calls for Dialnet
on SU-AI's WAITS timesharing system.  It may or may not get updated in
synchronization with the system; in particular, the system may have
things that haven't made it here yet, or things may be described here
that aren't in the system yet.  Anybody who wishes to write a user
program for the Dialnet port should contact MRC first.

     The Dialnet port is device DLN.  If there is more than one
Dialnet port, it is device DLN0, DLN1,...  The Vadic 1200/1200 baud
modem is DLN0 and the Dialnet debugging kludge is DLN1 and DLN2.  DLN
is NOT a shared device; whomever is using a Dialnet line has it
without interference from other jobs.

     Bits are specified as a decimal fraction: the integer part is the
quarter-word, numbered from right to left, and the fraction is the bit
within that quarterword; hence bit 1.1 is the low order bit and bit
4.9 is the sign bit.
How to snarf and free the Dialnet port:

     Currently, DLN must be opened in dump mode (mode 17).  Buffered
mode I/O will perhaps be supported in the future, although there won't
be any advantage to using it, since DLNSER buffers in the system for
the entire window.

     Consequently, to get a Dialnet port, you do one of:

	INIT ch,17		|	OPEN ch,[17
	 SIXBIT/DLNn/		|		 SIXBIT/DLNn/
	 0			|		 0]
	 <error return>		|	 <error return>
	<success return>	|	<success return>

     To give up the Dialnet port, you do:

	RELEASE ch,

which frees up the port and the I/O channel, and releases the system
buffers allocated for the window.
How to do I/O to the Dialnet port:

     I/O to the Dialnet port is done with the INPUT and OUTPUT UUO's.
An attempt to do Dialnet I/O when there is no process connection will
type an error message and stop the job.

The I/O UUO's are in the form:

	uuo ch,block	(uuo is INPUT or OUTPUT)
	<return>

block:	<byte pointer to user buffer>
	<byte count for user buffer>
	<channel>

     Don't use IN or OUT.  They will skip return under certain
circumstances which are "errors" with other devices, but not with
Dialnet.

     Normally, the UUO's will go into an I/O wait state if (on input)
the buffer is empty or (on output) the window is full.  By setting the
3.6 bit in the byte pointer (the unused bit in a byte pointer), either
of these states will cause the UUO to return with an updated byte
pointer and byte count.  This is useful in certain cases to avoid
deadly embraces.

     If the size field of the byte pointer is zero (ie, the 3.7 to 4.3
bits), then DLNSER will set up a 9.-bit byte pointer starting with the
4.9 bit of the word (ie, the byte pointer is set up with 441100 in the
left half).  The 3.6 bit is not altered in any case.

     The channel number argument has two purposes: on OUTPUT it sets
the channel number in the packet.  On INPUT, it says what channel to
be "read" on.  If the current packet on the input list is not for that
channel, the UUO returns, with the channel number of the current
packet returned in the block.  Of course, if some data was read on the
desired channel before it hit a packet on a different channel, the
data was read in, and the byte pointer and byte count have been
suitably updated.  This is the way you detect channel changes.  Note
that if you use the 3.6 bit to not wait, you must check the channel
number argument to see if it changed before assuming that you ran out
of input!

     9.-bit I/O is the official way to do I/O on pdp10 machines for
Dialnet.  The msb is guaranteed to be zero.  The reason why 9.-bit is
recommended over 8.-bit is that the 4 bits are wasted anyway, and it
is much easier to read bytes stored in quarter words than 8.-bit
bytes.  Since numbers are read on the pdp10 in octal and the pdp10 is
a 36.-bit machine, 9.-bit user bytes is the desireable size.  On an
IBM 370, with a 32.-bit word and reading in hexadecimal, 8. bits is
the correct size.  Note that the 9. bit is ignored and never set by
the system, and that user programs should do the same.

     Note that as in other system calls, it is NOT possible to use
indirection or indexing on the byte pointer.  DLNSER will turn off
these bits if they are set.  User programs should not rely upon this
however and should leave the bits clear.  It is trivial for a user
program to do the effective address calculation if indirection or
indexing is needed before doing the UUO.

     When an EOF occurs in the data stream, IO%EOF is set, the channel
the EOF was on is returned in the channel number argument, and the UUO
returns, regardless of whether or not bit 3.6 is set or the byte count
has run out.  This applies also to a CLS, since it sets IO%EOF.

     A received INT packet causes an INTINS new-style interrupt to
happen.  This is bit 3.6 in the interrupt word.  Look in the UUO
manual under "new-style interrupts" for more information.  This
happens immediately, and IO%INT is set in the I/O status word.

     A received CLS packet sets IO%CLS immediately; and clears IO%CON
and sets IO%EOF when processed by an INPUT UUO.  The CLS reply is
sent at INPUT UUO level as well.  In addition, the job gets an INTIMS
interrupt immediately.  A phone hangup behaves in a similar way;
however, the connection and all related information is instantly
flushed as if a RELEASE UUO was done.  A job should enable for INTIMS
and check IO%CON to determine which condition happened, if it cares
about whether the connection was closed or the line hung up.

     The following I/O UUO's are illegal when done on a Dialnet port
channel: ENTER, LOOKUP, USETO, USETI, UGETF, RENAME, and UTPCLR.
How to do command functions to the Dialnet port:

     All "command" functions to the Dialnet port are done by using the
MTAPE UUO.  The effective address of the UUO points to a command
block.  The format is:

	MTAPE ch,block
	<return>

block:	function
	<command arguments>

     The function is a small integer (which indexes into a
function dispatch table).  An illegal command stops the job with
an illegal UUO message.

     The functions are:

MTAPE function 0	Connect to remote process

	MTAPE ch,block
	 <dialer lossage, dialer byte in block>
	<return>

block:	0
	<high order 4 characters of PID in 9-bit ASCII>
	<low order 4 characters of PID in 9-bit ASCII>
	<initial window size>
	<up to four words of phone number or 0 to not dial>

     This function sends an RPC (Request Process Connection) to the
remote site.  There must not be a process connection already on the
channel.  The process ID is an ASCII string packed 4 per word as 9
bit bytes.  The initial window size is what we allocate to the
remote site and defaults to 2.  The maximum window size is 16.
packets, the minimum is 2.


MTAPE function 1	Close process connection

	MTAPE ch,block
	<return>

block:	1

     This function sends a CLS (CLoSe process connection) to the
remote site.  There must be a process connection on the channel.  No
further OUT's are allowed.  Incoming MSG packets will be accepted
until the CLS' packet is acknowledged, after which they will be
rejected.

     The CLOSE UUO is the same as MTAPE function 1.

MTAPE function 2	Set window size

	MTAPE ch,block
	<return>

block:	2
	<window size>

     This function sends a WIN (set WINdow size) to the remote site
and allocates <window size> windows.  The default window size is 2,
2≤window≤16.


MTAPE function 3	End of file

	MTAPE ch,block
	<return>

block:	3
	<channel>

     This function sends an EOF (End Of File) to the remote site on
the specified Dialnet logical channel.  EOF is interpreted in whatever
way the user-level protocol wishes; in FTP it indicates the end of a
data stream sent on an auxillary channel.


MTAPE function 4	Interrupt

	MTAPE ch,block
	<return>

block:	4
	<channel>

     This function sends an INT (INTerrupt) to the remote site on the
specified Dialnet logical channel. INT is interpreted in whatever way
the user-level protocol wishes; in FTP it indicated the abnormal
interruption and termination of a data stream sent on an auxillary
channel.


MTAPE function 5	Force buffer out

	MTAPE ch,block
	<return>

block:	5

     This function forces the current packet out but does no other
processing.  Note that if the window has filled up this UUO will NOT
return until the window has opened up.

MTAPE function 6	Get Dialnet status

	MTAPE ch,block
	<return>

block:	6
	<I/O status returned here>
	<connection's process ID returned here>
	<second byte of process ID returned here>
	<input window size returned here>
	<output window size returned here>

     The status bits which are relevant to users are:

Name	Bit value	Number	Meaning

IO%INT	     0,,100	1.7	interrupt in input stream
		Interrupt received.  This bit is set when an INPUT
		UUO reaches the point in the data stream where an
		INPUT occured.
IO%CLS	     0,,200	1.8	connection closing
		Connection is closed or is closing.  IO%EOF says
		whether or not there is any data available.
IO%EOF	     0,,400	1.9	end of file in input stream
		"End of input" has occured.  This means one of
		two things:
		[1]  If IO%CLS is clear, an EOF was received.
		[2]  If IO%CLS is set, connection is closed,
		     and no more data is available.
IO%DTM	     0,,1000	2.1	data missed due to user being too slow
		This is a warning that the input list exceeded the
		window size at least once, and DLNSER was forced to
		discard perfectly good data packets.  This is a defence
		against infinite packets piling up in the system and
		eating all of free storage.  It means the user program
		is not reading the input stream fast enough (probably
		a user bug, hung or stopped with ↑C).

     Other Dialnet-specific bits used internally by the system are:

IO%CON	   200,,0	3.8	connection open
IO%CCR	   400,,0	3.9	carrier detect on this line
IO%RDY	  2000,,0	4.2	got a good packet from the other side
IO%IDL	  4000,,0	4.3	Output idle
IO%DLE	 10000,,0	4.4	DLE seen at DLIINT
IO%EOP	 20000,,0	4.5	RDPDUN to be run at EOP
IO%R1B	 40000,,0	4.6	read one byte into DDB's DREP
IO%ACN	100000,,0	4.7	need to send acknowledgement
IO%ODE	200000,,0	4.8	need to output an additional DLE
IO%LIC	400000,,0	4.9	locally initiated connect, set at DLNRPC

     A GETSTS UUO can be used to get these status bits.  STATZ and
STATO can be used to test the user bits.  SETSTS can be used to set
or clear the users bits (it is only meaningful to clear these bits).
Other bits, as described in the UUO manual, may or may not be set,
but users should not use these bits.  In particular, none of the "I/O
error" bits are set or used by DLNSER.

     The process ID is zero iff there is no connection.  If the
process ID is non-zero but the IO%CON bit is off, then the connection
is "half-opened"; in other words, an RPC has been sent (or received)
but has not yet been accepted (or refused).  Presumably a user program
would know whether or not it provoked a connection (!).  The process ID
is in the form of 9.-bit bytes.

MTAPE function 7	Wait for connection

	MTAPE ch,block
	 <connection rejected>
	<return>

block:	7

     This function is used to wait for a connection (initiated by
MTAPE 0) to be completed.  It will hang until either a connection is
established or the PID clears, indicating the connection was refused.


MTAPE function 10	Performance statistics

	MTAPE ch,block
	<return>

block:	10
	size of data block to be returned
	data block

     This function returns a set of Dialnet performance counters.  What
are in the counters is subject to change.  Currently they are:

Cell	Description

NINPKT	# of packets read
NOUPKT	# of packets sent
NORPKT	# of retransmitted packets
NFRERR	# of framing errors
NCKERR	# of checksum errors
NRCERR	# of local errors reported by remote
NSNERR	# of remote errors we reported
NRNERR	# of NAK's received
NDOERR	# of data overruns (probably user error)
NNSERR	# of MAKPDB failures due to no FS
NRSERR	# of REPFPL failures due to no FS
NDLERR	# of dialer abort failures
NSQERR	# of sequence errors
NRPERR	# of redundant packet errors
NCRTRN	# of clock-level retransmissions